home *** CD-ROM | disk | FTP | other *** search
/ Ultimedia 2 / Ultimedia 2.iso / tools / soundtools / xmodule / xmodule.doc < prev    next >
Text File  |  1994-07-30  |  21KB  |  494 lines
  1.  
  2.  
  3.    This manual documents XModule version 2.8 released on 28 Jul 94.
  4.  
  5.    Copyright (C) 1993-1994 by Bernardo Innocenti, Freely distributable,
  6. all rights reserved.
  7.  
  8. Overview
  9. ********
  10.  
  11.    The Amiga computer has standard file formats for almost everything.
  12. Graphics, text, animation, hypertext and many other data types are
  13. easily imported into any program that supports the given standards.
  14. But this isn't true for music.  Too bad the music interchange file
  15. format defined by Electronic Arts (the old IFF SMUS) was too poor to be
  16. usable in high-quality music sequencers.  Therefore, every music editor
  17. created its own proprietary module format, so that, for instance, you
  18. cannot load into ProTracker music written with Oktalyzer.
  19.  
  20.        XModule (pronounced Cross Module) born as music module
  21. conversion utility that tries to solve this problem.  The project
  22. started in early 1993, as a friend of mine (Fabio), who wrote a lot of
  23. (good) music on Oktalyzer, needed ProTracker to obtain certain effects.
  24. He had an old PD conversion program called Tracker that worked only
  25. in particular conditions and was really bogus.  So I decided to contact
  26. the author and he let me have the source for Lit30000  (about $20).
  27.  
  28.    The original program has been completely rewritten from scratch, as
  29. the source was really poorly coded.  At the moment, Oktalyzer,
  30. ProTracker, NoiseTracker and SoundTracker are the only supported
  31. formats, but I'm still developing XModule, so contact me if you want to
  32. see your favorite music editor added to this (short) list (see Author
  33. Info).
  34.  
  35.    Now XModule sports many other features, like module optimization, a
  36. nice user interface and complex module editing.  This is why I like to
  37. call XModule a module processor.  XModule is to the music processing
  38. what ADPro and ImageFX are to image processing (am I a bit immodest?
  39. :-).
  40.  
  41. Distribution
  42. ************
  43.  
  44.    XModule is a Freeware program.  This means that you (probably)
  45. have got it free and you should not ask any money if you decide to
  46. copy it for someone else.  If, instead, someone sold you XModule for a
  47. price higher than the media used to store it on (i.e. $1 for a DD
  48. disk), tell him he should try making money honestly.
  49.  
  50.    I'm not asking you to pay for XModule because I never paid for a
  51. ShareWare program, so I felt that I somehow had to pay my debt and I
  52. decided to distribute XModule as free software, a little gift to all
  53. the Amiga community.  Feel free to distribute XModule to your friends
  54. and enemies, but, if you do so, you must keep the documentation and
  55. the other distribution files together with the executable.  The source
  56. code is not required, but I'm distributing it to let others take
  57. advantage of my work, so, if possible, try to include the source too.
  58.  
  59.    Fred Fish, SAN, ADS and Aminet are especially granted permission to
  60. include XModule into their PD libraries.  Other PD libraries are
  61. welcome as well.
  62.  
  63.    If you intend to include XModule or parts of it in a commercial
  64. package, please at least send me a free copy of the product.  I would
  65. be honored to see one of my programs being part of a commercial package.
  66.  
  67.    You can modify or improve XModule (see Programmers), only be so kind
  68. to return the new source code to me, so I can put the new features in
  69. the next release.  And, please, do not strip my name from the
  70. documentation, the program source, or the executable.
  71.  
  72.    This product is provided as is, without warranties of any kind:
  73. the author of this program cannot be held liable for any defects in the
  74. executable nor in the documentation or in any other files contained in
  75. this package.  Any damage directly or indirectly caused by the
  76. use/misuse of XModule is the sole responsibility of the user her/him
  77. self.  In other words: XModule never formatted my hard disk nor killed
  78. my dog, so I suppose it won't cause any damage to your system either,
  79. but, just in case, do not blame me if something nasty happens.
  80.  
  81. Getting Started
  82. ***************
  83.  
  84.    XModule requires KickStart version 2.0 or greater.  The reason is
  85. that I hate programming on 1.3 and I won't do it any more.  If you still
  86. haven't upgraded to 2.0, you'll miss the chance to run XModule and many
  87. other wonderful programs.  So what are you waiting for?
  88.  
  89.    XModule also takes advantage of some 3.0 features, like DataTypes,
  90. AmiGaGuide, Locale and some enhancements for the user interface.
  91.  
  92.    You can invoke XModule either from the Shell or Workbench.  XModule
  93. accepts both command line and ToolTypes arguments.  Workbench and Shell
  94. parameters are the same.  The full AmigaDOS template is:
  95.  
  96.      XModule FROM/M,PUBSCREEN/K,PORTNAME/K
  97.  
  98. The FROM keyword specifies optional modules to load at startup time.
  99. From Workbench, you multi-select module icons instead of specifying a
  100. ToolType.
  101.  
  102.    Specifying the PUBSCREEN keyword, followed by a public screen name,
  103. allows you to open XModule on an existing public screen.  The given
  104. name should match exactly (case matters), or the system won't be able to
  105. find the requested screen.  If the screen does not exist, a new public
  106. screen will open, cloning Workbench resolution and palette.  Note that
  107. this behavior is not standard: Commodore commodities will abort if the
  108. required public screen does not exist.  The default for this option is
  109. "Workbench", that will open XModule on the Workbench screen.
  110.  
  111.        PORTNAME will change the name of XModule's ARexx port.  If a
  112. port with this name already exists, a number (eg: ".1") will be
  113. appended to the name, until a unique name is found.  The port name
  114. defaults to "XMODULE".  For more about the ARexx port, consult the
  115. ARexx Interface chapter.
  116.  
  117. User Interface
  118. **************
  119.  
  120.    XModule's GUI follows Commodore's 2.0 style guidelines.  Under
  121. Kickstart 3.0 and above, XModule takes advantage of some new OS
  122. capabilities to enhance some aspects of the GUI.
  123.  
  124.    Gadget layout is font sensitive, but using some fancy fonts could
  125. give you a strange user interface look.  If you are using a very big
  126. font and a window becomes too big to fit in the screen, topaz/8 will
  127. be used as a fallback for rendering that window.  When you close a
  128. window, it will remember its position and size when you open it again.
  129. The same applies to window zooming.
  130.  
  131.    In all windows, the following shortcut keys are active:
  132.  
  133. ESC
  134.      Close the active window.  Does not work with ToolBox window, as it
  135.      would make it too easy to accidentally exit the program.
  136.  
  137. HELP
  138.      Bring up AmigaGuide on-line help.  This feature requires
  139.      amigaguide.library, which is part of Workbench 2.1 and up,
  140.      and XModule.guide located in the current directory or in the
  141.      same directory of XModule's executable or in HELP:language/
  142.      directory, where language is one of your Locale preferred
  143.      languages.
  144.  
  145. TAB
  146.      Cycle forward through string and numeric gadgets within the active
  147.      window.  SHIFT-TAB will cycle backwards.  TAB also activates
  148.      the first string or numeric gadget if none is selected.
  149.  
  150. Cursor up/down
  151.      Move up and down in a viewlist whenever the active window contains
  152.      one.  SHIFT-Cursor moves 5 items up/down. ALT-Cursor moves to
  153.      the top or to the bottom of the list.
  154.  
  155.    In addition, gadgets with underscored characters in labels, can be
  156. selected hitting the highlighted key.  SHIFT-key acts the opposite of
  157. the unshifted key (sliders are decremented by one, cycle gadgets will
  158. cycle backwards, etc).
  159.  
  160. Panels
  161. ******
  162.  
  163.    Sorry, XModule's documentation is still incomplete.  The next release
  164. will hopefully be more accurate.
  165.  
  166.    But wait! Do not commit suicide for such a reason: XModule is very
  167. easy to use, and you will be able to operate it even without this
  168. chapter.
  169.  
  170. ToolBox Window
  171. ==============
  172.  
  173.    Gadgets:
  174.  
  175.    Project Menu:
  176.  
  177. Format Conversion
  178. *****************
  179.  
  180.    XModule can load and save modules created by other music editors.
  181. The following is a list of supported module formats:
  182.  
  183. * NoiseTracker
  184.      Noise/ProTracker 31 instruments module.  This is the default.
  185.  
  186. * ProTracker 2.3
  187.      ProTracker 2.3 new 100 patterns module.  XModule will automatically
  188.      switch to ProTracker 100 whenever the converted module exceeds
  189.      the 64 patterns limit.
  190.  
  191.          Warning: You must load such a module with ProTracker 2.3 or
  192.      better in order to play/edit it.  Older players will either refuse
  193.      to load or turn the module into scratch dance.
  194.  
  195. * SoundTracker 15 instrument module
  196.      This is pretty useless as SoundTracker is becoming quite rare.  Do
  197.      not save SoundTracker modules unless you really need to, because
  198.      most players/editors will stop supporting this format very soon.
  199.      SoundTracker format has no way of identifying a module, therefore
  200.      XModule will ask you to confirm a SoundTracker module when the
  201.      file being loaded matches no other module format.
  202.  
  203. * UnicTracker
  204.      Actualy I've never seen UnicTracker, but I sometimes ripp Unic
  205.      modules with ExoticRipper, so I decided to give support for this
  206.      weird Tracker clone too.  The format is very similat to
  207.      ProTracker, except for the EMW3 ID.
  208.  
  209. * Oktalyzer V1.1
  210.      Oktalyzer is an old editor which can play up to 8 channels by
  211.      mixing instruments in real time.
  212.  
  213.    As a matter of fact, there are things that simply cannot be done
  214. because of the big differences between module formats.  Below is a list
  215. of the internal limitations of each module formats.  When you save to a
  216. particular format, if the module exceeds one of this values, or makes
  217. use of features not implemented, some data will be stripped away to
  218. produce at least a partial conversion.
  219.  
  220.  
  221.      Program          Instr  MaxPatt PattLen SongLen InstrLen
  222.      --------------------------------------------------------
  223.      Oktalyzer         36      128     128     128     128K
  224.      Sound Tracker     15       64      64     128      64K
  225.      Noise Tracker     31       64      64     128      64K
  226.      Pro Tracker       31      100      64     128      64K
  227.      MED/OctaMED       63      256     256     256   No Limit
  228.      
  229.      Where:
  230.      #Instr   is the maximum number of instruments,
  231.      MaxPatt  is the maximum number of patterns,
  232.      PattLen  is the maximum number of lines per pattern,
  233.      SongLen  is the maximum number of positions in a song,
  234.      InstrLen is the maximum size of an instrument given in bytes.
  235.  
  236.    Effects are the hardest thing to convert.  While Speed and Volume
  237. are almost the same between different music editors, some effects (such
  238. as Oktalyzer's H and L) cannot be converted because there are no
  239. equivalents in other music editors.  Therefore, you will have to modify
  240. the score manually if you intend to convert a module while keeping such
  241. effects.  In addiction, some effects behave in different ways even if
  242. they claim to do the same thing.
  243.  
  244.    Last but not least, some music editors support synthetic or hybrid
  245. instruments.  Fortunately, none of the module formats known by XModule
  246. implement such instruments, because I can hardly think of a way to
  247. implement a sample to synth conversion (any ideas?).  I used to like
  248. synthetic music, but it seems that all those great composers on the
  249. good old C64 have vanished...  Why have you musicians become so lazy?
  250. 8-(
  251.  
  252. Optimization
  253. ************
  254.  
  255.    Module optimization is achieved by removing all unused data in such
  256. a way that the module will sound the same as before.  XModule can
  257. process a module to reduce its size as much as possible.  It is
  258. generally a good idea to optimize a module before distributing it, but
  259. never while you are still composing it, because you could easly loose
  260. some data that you didn't want to discard.  Do not expect to gain a lot
  261. of bytes optimizing modules: saving 20% of the total size is usually a
  262. very good result.
  263.  
  264. * Unused patterns
  265.      Some formats (e.g.: Sound/Noise/ProTracker) store empty patterns
  266.      in a module if a pattern with a greater number is used.  For
  267.      instance, a song using patterns 1, 2 and 5 will contain patterns 3
  268.      and 4 as well.
  269.  
  270.          Warning: If a song contains a part that has not been finished
  271.      yet and has not already been inserted in the position table, you
  272.      will lose it.
  273.  
  274.          Warning: When a song is saved to Noise/ProTracker, patterns
  275.      beyond the last used patterns are discarded regardless of this
  276.      switch.  This is due to a limitation of Noise/ProTracker module
  277.      format.
  278.  
  279. * Unused instruments
  280.      A composer may decide to use an instrument and then change his
  281.      mind, but forget to clear the instrument.  In this case the module
  282.      will contain an instrument that is never played.  These instruments
  283.      are simply stripped away.
  284.  
  285. * Sample data after a loop
  286.      The part of an instrument following a loop is never played and is
  287.      therefore discarded.
  288.  
  289. * Instruments zero tails
  290.      Long zero tails eat up memory and produce no sound.  This
  291.      optimization is performed only on loopless instruments, as a zero
  292.      sequence inside a loop does make difference.  XModule leaves at
  293.      least two zero bytes to avoid the nasty click produced by the
  294.      speaker dropping its volume to zero too quickly.
  295.  
  296. ARexx Interface
  297. ***************
  298.  
  299.    Sorry, XModule's documentation is still incomplete.  The next release
  300. will hopefully be more accurate (it's already three releases I'm
  301. promising it :-).
  302.  
  303.    Anyway, XModule's ARexx port is a little brain dead at the moment,
  304. so you're not missing a great deal.
  305.  
  306. Known Bugs
  307. **********
  308.  
  309.    Murphy's laws state that nothing can be perfect, not even computer
  310. programs.  XModule is far from being perfect and I need your help to
  311. fix as many bugs as possible.  If you discover a bug which isn't
  312. reported in the list below (note: there is no list at the moment; this
  313. is a beta release, remember?), please notify me.
  314.  
  315.    When you report a bug, state exactly what happens and indicate how
  316. to reproduce the conditions that generated the problem.  Reports like
  317. `XModule sometimes crashes converting my favorite module' does not help
  318. at all.  Include your name if you want to be credited in future XModule
  319. releases.
  320.  
  321.    If the program refuses to convert a module, mail it to me on a disk
  322. or upload it to a BBS that I can reach and I'll try to fix the problem
  323. as soon as possible.  Glass Globe BBS, whose address can be found in
  324. the Author Info chapter, will do.  If you want the disk back with the
  325. fixed version of XModule, send me a self-addressed envelope with enough
  326. italian stamps or enough money for a reply.
  327.  
  328.    XModule has been tested on several machines running Kickstart 2.0,
  329. 3.0 and 3.1.  It should work on any 68K family processor (tested on
  330. 68000, 68020 and 68040) and is Enforcer and Mungwall proof.  I also
  331. tested XModule with virtual memory programs (such as VMM40) and found
  332. that everything seems to work correctly.
  333.  
  334. Future plans
  335. ************
  336.  
  337. * OctaMED
  338.      This will probably be the next format I'll work on.  I think this
  339.      is the best music editor available on the Amiga, but I haven't yet
  340.      got enough infos on its file format to code a conversion routine.
  341.      If you have such information, please contact me (see Author Info).
  342.  
  343. * TeX
  344.      Another format I would like to add is AmigaTeX.  If you know TeX,
  345.      you will surely be wondering what a typesetting program can be
  346.      used for in music.  Well, AmigaTeX is at the moment is the best
  347.      implementation available on any computer of the TeX typesetting
  348.      program, and its distribution includes MusicTeX, a powerful
  349.      music language which can output notes in a great standard staff
  350.      notation.  I know no other program on the Amiga that can print
  351.      notes of such fine quality (if you do, let me know!), so I think
  352.      that many musicians would appreciate such an option.
  353.  
  354. * Other module formats
  355.      If you have documentation regarding a format you would like to see
  356.      in a next release, please send it to me together with a couple of
  357.      modules and, if possible and legal, the program that created them.
  358.      I'll try to implement the new format only if it is somewhat easy:
  359.      it is very hard to convert, say, Future Composer to SoundTracker.
  360.      Do not send a module without a text file describing its structure,
  361.      as I'm not willing to spend my nights hex-dumping modules :).
  362.  
  363. Programmer notes
  364. ****************
  365.  
  366.    XModule has been written in C and compiled with SAS C version 6.51,
  367. Other compilers may require some changes to the source.
  368.  
  369.    The program is written in respect of the Amiga multitasking
  370. operative system and complies with Commodore programming guidelines.
  371. All allocated resources will be (hopefully) freed before program
  372. termination.  I wrote XModule with the goal in mind of keeping the
  373. executable fast and small.
  374.  
  375.    This manual has been typeset using MakeInfo, a GNU PD utility ported
  376. to the Amiga by Reinhard Spisser and Sebastiano Vigna.  I found that
  377. the time I saved writing one file for three was nearly compensated by
  378. the time I spent learning how to operate MakeInfo.  As I'm not that
  379. skilled in using TeX and MakeInfo, you will probably find this document
  380. a bit silly in its typesetting style.
  381.  
  382.    Besides, English is not my first language (as you might have
  383. guessed) and I bet this document is full of grammar mistakes.
  384.  
  385.    If you intend to translate, improve or somewhat edit this document,
  386. please work on the supplied TexInfo file and then process it with the
  387. utilities supplied in the MakeGuide distribution.  You can find
  388. MakeGuide in several PD libraries such as BBSs.
  389.  
  390.    Do not hesitate to send criticisms to my work, and, even better,
  391. advices on how to improve the program and the documentation.  See
  392. Author Info.
  393.  
  394. Credits
  395. *******
  396.  
  397.    * Fabio Barzagli, for beta testing version 1.x, for the money he
  398.      paid me for it and, last but not least, for letting me have (or
  399.      steal?) his awesome modules!
  400.  
  401.      Keep on making good music, Fabio!
  402.  
  403.    * Alessandro Lombardi, for 2.x beta testing.
  404.  
  405.      Stop deleting files!
  406.  
  407.    * Massimo Brogioni, for being my fido boss and for spreading bogus
  408.      XModule releases all around the world.
  409.  
  410.      Hey boss, have you got a spare 5Gig streamer?
  411.  
  412.    * Erno Tuomainen for his wonderful Finnish BBS, for his kindness and
  413.      for all the support he gave me.
  414.  
  415.      Are there any more top-rating modules to leech?
  416.  
  417.    * Gerardo Iula, for letting me have the source of Tracker (by paying
  418.      :-( ).
  419.  
  420.      I assumed the money I paid covered the rights of modifying the
  421.      original source and distributing modified versions of your
  422.      program.  Hope you won't worry about it, Gerardo.
  423.  
  424.    * Sebastiano Vigna & his buddy Reinhard Spisser, for porting GNU
  425.      MakeInfo to the Amiga and for Reinhard's E-Mail technical support.
  426.  
  427.      Please, continue developing this useful (and hard to learn) tool.
  428.      By the way, MakeInfo crashed my Amiga really bad a couple of times!
  429.      Are my docs that boring?
  430.  
  431.    * The Amiga, for being the best computer in the world. :^)
  432.  
  433.      Commodore: Why don't you sell the Amiga project to someone serious
  434.      such as GVP or NewTek?
  435.  
  436. How to contact the author
  437. *************************
  438.  
  439.    If you want to make me aware of your suggestions, bug reports, ideas
  440. or you want to send me a gift, a good module or, why not, some money
  441. :-), reach me in any of the following ways:
  442.  
  443. * Mail
  444.           Bernardo Innocenti
  445.           Via Ventiquattro Maggio, 14
  446.           50129 - Firenze
  447.           ITALY
  448.  
  449. * FAX
  450.           +39-55-8877771
  451.           Attn:  Bernardo Innocenti
  452.           Subj:  Amiga/XModule
  453.  
  454. * E-Mail
  455.           AmigaNet: Bernardo Innocenti 39:102/201.4
  456.           FidoNet:  Bernardo Innocenti 2:332/118.4
  457.           UseNet:   bernie@nikita.nervous.com
  458.           (Glass Globe BBS ++39-577-959054)
  459.  
  460.    I will try to reply to all my E-Mail, but I'm too lazy to reply
  461. old-style mail.  Your suggestions will be taken into account unless
  462. they are `I want XModule to do ice tea'-style.
  463.  
  464. Concept Index
  465. *************
  466.  
  467.  
  468.  
  469.  Acknowledgements                       Credits
  470.  Arguments, command line                Getting Started
  471.  Author's address                       Author Info
  472.  Bug reports                            Known Bugs
  473.  Bugs, known ones                       Known Bugs
  474.  Compiling                              Programmers
  475.  Contact the author, how to             Author Info
  476.  Credits                                Credits
  477.  Distribution                           Distribution
  478.  For programmers                        Programmers
  479.  GUI                                    User Interface
  480.  How to contact the author              Author Info
  481.  Known Bugs                             Known Bugs
  482.  Modifying XModule                      Programmers
  483.  Optimization                           Optimization
  484.  Overview of XModule                    Overview
  485.  Panels                                 Panels
  486.  Starting XModule                       Getting Started
  487.  Thanks                                 Credits
  488.  ToolTypes                              Getting Started
  489.  Usage                                  Getting Started
  490.  User Interface                         User Interface
  491.  Windows                                Panels
  492.  XModule overview                       Overview
  493.  
  494.